---
sidebar_label: Upgrade plugins
description: These are general upgrade instructions for OpenBao plugins.
---

# Upgrading OpenBao plugins

## Plugin upgrade procedure

The following procedures detail steps for upgrading a plugin that has been mounted
at a path on a running server. The steps are the same whether the plugin being
upgraded is built-in or external.

### Upgrading auth and secrets plugins

The process is nearly identical for auth and secret plugins. If you are upgrading
an auth plugin, just replace all usages of `secrets` or `secret` with `auth`.

1. [Register][plugin_registration] the first version of your plugin to the catalog.
   Skip this step if your initial plugin is built-in or already registered.

    ```shell-session
    $ bao plugin register \
        -sha256=<SHA256 Hex value of the plugin binary> \
        secret \
        my-secret-plugin
    ```

1. [Mount][plugin_management] the plugin. Skip this step if your initial plugin
   is already mounted.

    ```shell-session
    $ bao secrets enable my-secret-plugin
    ```

1. Register a second version of your plugin. You **must** use the same plugin
   type and name (the last two arguments) as the plugin being upgraded. This is
   true regardless of whether the plugin being upgraded is built-in or external.

    ```shell-session
    $ bao plugin register \
        -sha256=<SHA256 Hex value of the plugin binary> \
        -command=my-secret-plugin-1.0.1 \
        -version=v1.0.1 \
        secret \
        my-secret-plugin
    ```

1. Tune the existing mount to configure it to use the newly registered version.

   ```shell-session
   $ bao secrets tune -plugin-version=v1.0.1 my-secret-plugin
   ```

1. If you wish, you can check the updated configuration. Notice the "Version" is
   now different from the "Running Version".

   ```shell-session
   $ bao secrets list -detailed
   ```

1. Finally, trigger a [plugin reload](/docs/commands/plugin/reload) to reload all
   mounted backends using that plugin or a subset of the mounts using that plugin
   with either the `plugin` or `mounts` flag respectively.

    ```shell-session
    $ bao plugin reload -plugin my-secret-plugin
    ```

Until the last step, the mount will still run the first version of `my-secret-plugin`. When
the reload is triggered, OpenBao will kill `my-secret-plugin`’s process and start the
new plugin process for `my-secret-plugin` version 1.0.1. The "Running Version" should also
now match the "Version" when you run `bao secrets list -detailed`.

:::info

**Important:** Plugin reload of a new plugin binary must be
performed on each OpenBao instance. Performing a plugin upgrade on a single
instance or through a load balancer can result in mismatched
plugin binaries within a cluster. On a replicated cluster this may be accomplished
by setting the 'scope' parameter of the reload to 'global'.

:::

### Upgrading database plugins

1. [Register][plugin_registration] the first version of your plugin to the catalog.
   Skip this step if your initial plugin is built-in or already registered.

    ```shell-session
    $ bao plugin register
        -sha256=<SHA256 Hex value of the plugin binary> \
        database \
        my-db-plugin
    ```

1. [Mount][plugin_management] the plugin. Skip this step if your initial plugin
   is already mounted.

    ```shell-session
    $ bao secrets enable database
    $ bao write database/config/my-db \
        plugin_name=my-db-plugin \
        # ...
    ```

1. Register a second version of your plugin. You **must** use the same plugin
   type and name (the last two arguments) as the plugin being upgraded. This is
   true regardless of whether the plugin being upgraded is built-in or external.

    ```shell-session
    $ bao plugin register \
        -sha256=<SHA256 Hex value of the plugin binary> \
        -command=my-db-plugin-1.0.1 \
        -version=v1.0.1 \
        database \
        my-db-plugin
    ```

1. Update the database config with the new version. The database secrets
   engine will immediately reload the plugin, using the new version. Any omitted
   config parameters will not be updated.

    ```shell-session
    $ bao write database/config/my-db \
        plugin_version=v1.0.1
    ```

Until the last step, the mount will still run the first version of `my-db-plugin`. When
the reload is triggered, OpenBao will kill `my-db-plugin`’s process and start the
new plugin process for `my-db-plugin` version 1.0.1.

### Downgrading plugins

Plugin downgrades follow the same procedure as upgrades. You can use the OpenBao
plugin list command to check what plugin versions are available to downgrade to:

```shell-session
$ bao plugin list secret
Name                Version
----                -------
cassandra           v1.12.0+builtin.bao
kv                  v0.13.3+builtin
ldap                v1.12.0+builtin.bao
mysql               v1.12.0+builtin.bao
openldap            v0.9.0+builtin
pki                 v1.12.0+builtin.bao
postgresql          v1.12.0+builtin.bao
rabbitmq            v1.12.0+builtin.bao
ssh                 v1.12.0+builtin.bao
totp                v1.12.0+builtin.bao
transit             v1.12.0+builtin.bao
```

### Additional upgrade notes

* As mentioned earlier, disabling existing mounts will wipe the existing data.
* Overwriting an existing version in the catalog will affect all uses of that
  plugin version. So if you have 5 different Secrets mounts using the same plugin,
  they'll all start using the new binary if you overwrite it. We recommend
  treating plugin versions in the catalog as immutable, much like version control
  tags.
* Each plugin has its own data within OpenBao storage. While it is rare for OpenBao 
  maintained plugins to update their storage schema, it is up to plugin authors
  to manage schema upgrades and downgrades. Check the plugin release notes for
  any unsupported upgrade or downgrade transitions, especially before moving to
  a new major version or downgrading.
* Existing OpenBao [leases](/docs/concepts/lease) and [tokens](/docs/concepts/tokens)
  are generally unaffected by plugin upgrades and reloads. This is because the lifecycle
  of leases and tokens is handled by core systems within OpenBao. The plugin itself only
  handles renewal and revocation of them when it’s requested by those core systems.

[plugin_reload_api]: /api-docs/system/plugins-reload-backend
[plugin_registration]: /docs/plugins/plugin-architecture#plugin-registration
[plugin_management]: /docs/plugins/plugin-management#enabling-disabling-external-plugins
